<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Clipboard and ClipboardAll</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>

<body>
<h1>Clipboard and <a href="#ClipboardAll">ClipboardAll</a></h1>

<p><em>Clipboard</em> is a built-in <a href="../Variables.htm">variable</a> that reflects the current contents of the Windows clipboard if those contents can be expressed as text. By contrast, <em><a href="#ClipboardAll">ClipboardAll</a></em> contains everything on the clipboard, such as pictures and formatting.</p>
<p><a name="CopiedFiles"></a>Each line of text on <em>Clipboard</em> typically ends with carriage return and linefeed (CR+LF), which can be expressed in the script as <code>`r`n</code>. Files (such as those copied from an open Explorer window via Control-C) are considered to be text: They are automatically converted to their filenames (with full path) whenever <em>Clipboard</em> is referenced in the script. To extract the files one by one, follow this example:</p>
<pre><a href="../commands/LoopParse.htm">Loop, parse</a>, clipboard, `n, `r
{
    MsgBox, 4, , File number %A_Index% is %A_LoopField%.`n`nContinue?
    IfMsgBox, No, break
}</pre>
<p>To arrange the filenames in alphabetical order, use the <a href="../commands/Sort.htm">Sort</a> command. To write the filenames on the clipboard to a file, use <code><a href="../commands/FileAppend.htm">FileAppend</a>, %clipboard%`r`n, C:\My File.txt</code>. To change how long the script will keep trying to open the clipboard -- such as when it is in use by another application -- use <a href="../commands/_ClipboardTimeout.htm">#ClipboardTimeOut</a>.</p>
<strong>Basic examples:</strong>
<pre>clipboard = my text   <em>; Give the clipboard entirely new contents.</em>
clipboard =   <em>; Empty the clipboard.</em>
clipboard = %clipboard%   <em>; Convert any copied files, HTML, or other formatted text to plain text.</em>
clipboard = %clipboard% Text to append.   <em>; Append some text to the clipboard.</em>
StringReplace, clipboard, clipboard, ABC, DEF, All   <em>; Replace all occurrences of ABC with DEF (also converts the clipboard to plain text).</em></pre>

<p><strong>Using ClipWait to improve script reliability:</strong></p>
<pre>clipboard =  <em>; Start off empty to allow ClipWait to detect when the text has arrived.</em>
Send ^c
<a href="../commands/ClipWait.htm">ClipWait</a>  <em>; Wait for the clipboard to contain text.</em>
MsgBox Control-C copied the following contents to the clipboard:`n`n%clipboard%</pre>
<h2 id="ClipboardAll">ClipboardAll <span class="ver">(saving and restoring everything on the clipboard)</span></h2>
<p><em>ClipboardAll</em> contains everything on the clipboard (such as pictures and formatting). It is most commonly used to save the clipboard's contents so that the script can temporarily use the clipboard for an operation. When the operation is completed, the script restores the original clipboard contents as shown below:</p>
<pre>ClipSaved := ClipboardAll   <em>; Save the entire clipboard to a variable of your choice.
; ... here make temporary use of the clipboard, such as for pasting Unicode text via <a href="../commands/Transform.htm#Unicode">Transform Unicode</a> ...</em>
Clipboard := ClipSaved   <em>; Restore the original clipboard. Note the use of <i>Clipboard</i> (not <i>ClipboardAll</i>).</em>
ClipSaved =   <em>; Free the memory in case the clipboard was very large.</em></pre>
<p><em>ClipboardAll</em> may also be saved to a file (in this mode, FileAppend always overwrites any existing file):</p>
<pre><a href="../commands/FileAppend.htm">FileAppend</a>, %ClipboardAll%, C:\Company Logo.clip <em>; The file extension does not matter.</em></pre>
<p>To later load the file back onto the clipboard (or into a variable), follow this example:</p>
<pre><a href="../commands/FileRead.htm">FileRead</a>, Clipboard, <strong>*c</strong> C:\Company Logo.clip <em>; Note the use of *c, which must precede the filename.</em></pre>
<h3>Notes</h3>
<p><em>ClipboardAll</em> is blank when used in ways other than those described above. In addition, <em>ClipboardAll</em> is not supported inside <a href="../Variables.htm#comma">comma-separated expressions</a>; that is, it should be assigned on a line by itself such as <code>ClipSaved := ClipboardAll</code>.</p>
<p>Variables to which <em>ClipboardAll</em> has been assigned are in binary format and thus will appear as gibberish when displayed with <a href="../commands/MsgBox.htm">MsgBox</a> or similar. Also, altering a binary-clipboard variable (by means such as <a href="../commands/StringReplace.htm">StringReplace</a>) will revert it to a normal variable, resulting in the loss of its clipboard data. In v1.0.46+, binary-clipboard variables may be passed to <a href="../Functions.htm#ByRef">functions</a> by value (formerly they only worked <a href="../Functions.htm#ByRef">ByRef</a>).</p>
<p>If <em>ClipboardAll</em> cannot retrieve one or more of the data objects (formats) on the clipboard, they will be omitted but all the remaining objects will be stored.</p>
<p>A variable containing clipboard data can be copied to another variable as in this example: <code>ClipSaved2 := ClipSaved</code>.</p>
<p><a href="../commands/ClipWait.htm">ClipWait</a> may be used to detect when the clipboard contains data (optionally including non-text data).</p>
<p><a href="../commands/StringLen.htm">StrLen / StringLen</a> may be used to discover the total size of a variable to which <em>ClipboardAll</em> has been assigned. However, to get the size in bytes on Unicode versions of AutoHotkey, the length must be multiplied by 2. <a href="../Variables.htm#IsUnicode">A_IsUnicode</a> can be used to support ANSI and Unicode versions, as in this example: <code>size := StrLen(ClipSaved) * (A_IsUnicode ? 2 : 1)</code>.</p>
<p>Variables to which <em>ClipboardAll</em> has been assigned can be compared to each other (but not directly to <em>ClipboardAll</em>) by means of the &lt;&gt; and = operators. In the following example, the length of each variable is checked first. If that is not enough to make the determination, the contents are compared to break the tie:</p>
<pre>if ClipSaved1 &lt;&gt; %ClipSaved2%   <em>; This <u>must</u> be an old-style IF statement, not an expression.</em>
    MsgBox The two saved clipboards are different.</pre>
<p>Saving <em>ClipboardAll</em> to a variable is not restricted by the memory limit set by <a href="../commands/_MaxMem.htm">#MaxMem</a>.</p>
<p>A saved clipboard file internally consists of a four-byte format type, followed by a four-byte data-block size, followed by the data-block for that format. If the clipboard contained more than one format (which is almost always the case), these three items are repeated until all the formats are included. The file ends with a four-byte format type of 0.</p>
<p>Known limitation: Retrieving <em>ClipboardAll</em> while cells from Microsoft Excel are on the clipboard may cause Excel to display a &quot;no printers&quot; dialog.</p>
<p>Clipboard utilities written in AutoHotkey:</p>
<ul>
  <li>Deluxe Clipboard: Provides unlimited number of private, named clipboards to Copy, Cut, Paste, Append or CutAppend of selected text. <a href="http://www.autohotkey.com/forum/topic2665.html">www.autohotkey.com/forum/topic2665.html</a></li>
  <li>ClipStep: Control multiple clipboards using only the keyboard's Ctrl-X-C-V. <a href="http://www.autohotkey.com/forum/topic4836.html">www.autohotkey.com/forum/topic4836.html</a></li>
</ul>

<h2 id="OnClipboardChange">OnClipboardChange</h2>
<p>Scripts can detect changes to the content of the Clipboard by using <a href="../commands/OnClipboardChange.htm">OnClipboardChange</a>.</p>

</body>
</html>
